.TH std::front_insert_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::front_insert_iterator \- std::front_insert_iterator

.SH Synopsis
   Defined in header <iterator>
   template< class Container >

   class front_insert_iterator                                            \fI(until C++17)\fP

       : public std::iterator<std::output_iterator_tag, void, void,
   void, void>
   template< class Container >                                            \fI(since C++17)\fP
   class front_insert_iterator;

   std::front_insert_iterator is a LegacyOutputIterator that prepends elements to a
   container for which it was constructed. The container's push_front() member function
   is called whenever the iterator (whether dereferenced or not) is assigned to.
   Incrementing the std::front_insert_iterator is a no-op.

.SH Member types

   Member type       Definition
   iterator_category std::output_iterator_tag
   value_type        void
   difference_type   void           \fI(until C++20)\fP
                     std::ptrdiff_t \fI(since C++20)\fP
   pointer           void
   reference         void
   container_type    Container

   Member types iterator_category, value_type, difference_type, pointer
   and reference are required to be obtained by inheriting from           \fI(until C++17)\fP
   std::iterator<std::output_iterator_tag, void, void, void, void>.

.SH Member functions

   constructor     constructs a new front_insert_iterator
                   \fI(public member function)\fP
   operator=       inserts an object into the associated container
                   \fI(public member function)\fP
   operator*       no-op
                   \fI(public member function)\fP
   operator++      no-op
   operator++(int) \fI(public member function)\fP

.SH Member objects

   Member name           Definition
   container (protected) a pointer of type Container*

.SH Example


// Run this code

 #include <algorithm>
 #include <deque>
 #include <iostream>
 #include <iterator>
 #include <vector>

 namespace stb
 {
     void println(auto, auto const& d)
     {
         std::ranges::copy(d, std::ostream_iterator<int>(std::cout, " "));
         std::cout << '\\n';
     }
 }

 int main()
 {
     std::vector<int> v{1, 2, 3, 4, 5};
     std::deque<int> d;

     std::copy(v.begin(), v.end(),
               std::front_insert_iterator<std::deque<int>>(d));
               // or std::front_inserter(d)

     stb::println("{}", d);
 }

.SH Output:

 5 4 3 2 1

.SH See also

                        creates a std::front_insert_iterator of type inferred from the
   front_inserter       argument
                        \fI(function template)\fP
   back_insert_iterator iterator adaptor for insertion at the end of a container
                        \fI(class template)\fP
   insert_iterator      iterator adaptor for insertion into a container
                        \fI(class template)\fP
